Lists

Lists are a structural feature in Markdown. They're useful for many things, such as itemizing a collection of information, providing steps to a procedure, or numbering sections of information.

Syntax

There are two types of lists that can be created: Ordered Lists and Unordered Lists.

Ordered Lists are created by starting a line with a number or letter, followed by a single ., then space (two is recommended), then some text content.

Unordered Lists are created by starting a line with any -, *, or + character, followed by a space, then some text content.

Beyond these differences, both types of Lists have the same behavior when it comes to syntax and authoring.

Basics

Ordered List

Create a simple Ordered List using a number and a . character. Each list item is written on it's own line.

1.  list item one
2.  list item two
3.  list item three

Ordered Lists can also be created using letters and ..

a.  list item one
b.  list item two
c.  list item three

Roman numerals are fine, too. Remember to keep the vertical spacing consistent.

i.   list item one
ii.  list item two
iii. list item three

Re-using the same letter or number is OK.

1.  list item one
1.  list item two
1.  list item three

a.  list item one
a.  list item two
a.  list item three

Unordered List

Create a simple Unordered List using -. Each list item is written on it's own line.

- list item one
- list item two
- list item three

Unordered Lists can also be created using *.

* list item one
* list item two
* list item three

The + character can be used as well.

+ list item one
+ list item two
+ list item three

One Empty Line Between List Items

Put a single empty line between list items to give room. More than one empty line will break the list into two.

- list item one

- list item two

- list item three

Don't Use Unlike Characters

Using non-matching characters on the same list level will break the list in two.

- list item one
* list item one
+ list item one

1.  list item one
a.  list item one

Multi-Line Content in List Items

List Item content can span multiple lines. Use a blank line to separate elements. Make sure all lines of content retain the same vertical spacing.

1.  ### Cities in the US

    Here is a sample of some cities in the United States.

    | Name   | State    |
    |--------|----------|
    | Austin | Texas    |
    | Tulsa  | Oklahoma |

2.  list item two

- ### Cities in the US

  Here is a sample of some cities in the United States.

  | Name   | State    |
  |--------|----------|
  | Austin | Texas    |
  | Tulsa  | Oklahoma |

- list item two

Nested List Items

To nest List items, make sure the vertical spacing of the nested List item matches up with the content of the parent List item.

1.  list item one

    1.  nested list item one

2.  list item two

3.  list item three

- list item one

  - nested list item one

- list item two

- list item three

Nesting Different Types of Lists

Nesting Lists of different types is acceptable. Use the same spacing rules as usual.

1.  list item one

    - nested list item one

    - nested list item two

2.  list item two

3.  list item three

- list item one

  1.  nested list item one

  2.  nested list item two

- list item two

- list item three

Markdown++

A custom Paragraph Style can be given to a List using a Markdown++ style: command on the line directly above the List.

<!--style:CustomOList-->
1.  A customized ordered list, style name "CustomOList"
2.  CustomOList item two
3.  CustomOList item three

<!--style:CustomUList-->
- A customized unordered list, style name "CustomUList"
- CustomUList item two
- CustomUList item three

Customizing Nested Lists

Nested Lists can be customized as well.

1.  A default list, style name "OList"

    <!--style:CustomOList-->
    a.  A customized list, style name "CustomOList"

    b.  CustomOList item two

2.  OList item two

- A default list, style name "UList"

  <!--style:CustomUList-->
  - A customized list, style name "CustomUList"

  - CustomUList item two

- UList item two

Default Until Customized

Nested Lists are treated as standalone; they will not inherit the outermost stylename if customized.

<!--style:CustomOList-->
1.  A customized list, style name "CustomOList"

    a.  A default list, style name "OList"

    b.  OList item two

2.  CustomOList item two

<!--style:CustomUList-->
- A customized list, style name "CustomUList"

  - A default list, style name "UList"

  - UList item two

- CustomUList item two

Add a style: command to each list individually for consistency with custom styles.

<!--style:CustomOList-->
1.  A customized list, style name "CustomOList"

    <!--style:CustomOList-->
    a.  A customized list, style name "CustomOList"

    b.  CustomOList item two

2.  CustomOList item two

<!--style:CustomUList-->
- A customized list, style name "CustomUList"

  <!--style:CustomUList-->
  - A customized list, style name "CustomUList"

  - CustomUList item two

- CustomUList item two

Nested Content in Lists

The tagging convention can be used for other Markdown elements inside List items. The resulting style name will be appended with the style name of the containing List.

1.  <!--style:CustomParagraph-->
    A customized paragraph, style name "OList CustomParagraph"

2.  list item two

- <!--style:CustomParagraph-->
  A customized paragraph, style name "UList CustomParagraph"

- list item two

To learn more about Markdown++ tagging, see Learning Markdown++.

ePublisher Style Information

Style Behavior

To allow full styling of Lists, ePublisher creates a number of style names when a list is detected inside a Markdown source document.

List Style

The List Style is the first style that ePublisher adds to the Style Designer when a list is detected in a source document. The default name is OList for ordered lists, and UList for unordered lists, but could also be a custom name if the style: command is used on the list.

This style applies to the container area surrounding the lists's items. It's style rules can also apply to list items or nested content, if the same rule isn't already applied on a nested style.

Customizing the List Style

By adding a Markdown++ custom style: command, the List Style name can be changed. The example below changes the List Style name to CustomUList:

<!--style:CustomUList-->
- This is a custom list
- unordered
- named "CustomUList"

List Item Style

The list items inside a list also get a style name. To determine the List Item Style's name, ePublisher takes the List Style and adds Item to the end, separated by a space. The default name is OList Item for ordered list items, and UList Item for unordered list items, but could also be a custom name if the style: command is used on the list.

Customizing the List Item Style

By adding a Markdown++ custom style: command, the List Item Style name can be changed. The example below adds the List Item Style CustomUList Item, because the List Style name has been set to CustomUList:

<!--style:CustomUList-->
- This is a custom list
- unordered
- named "CustomUList"

List items can't be styled individually. This will break the list into two separate lists. All list items in a given list are styled by the same List Item Style.

Nested Styles

Nested content inside of list items also get a new style name. To determine the Nested Style's name, take the List Style and add the style name of the nested content to the end, separated by a space.

The example below populates the Style Designer with 3 Paragraph Styles: UList (the List Style), UList Item (the List Item Style), and UList Paragraph when scanned into ePublisher.

- This is a simple list
- unordered
- default style names

Customizing Nested Styles

By adding a Markdown++ custom style: command, the Nested Style name can be changed. The example below changes the Nested Style name to UList CustomParagraph:

- <!--style:CustomParagraph-->
  This is a custom paragraph.

Custom Style Names can be used on both the list and nested content simultaneously. This example creates the style names CustomUList, CustomUList Item, and CustomUList CustomParagraph:

<!--style:CustomUList-->
- <!--style:CustomParagraph-->
  This is a custom paragraph inside a blockquote.

Default Style Properties

Style Type: Paragraph
Style Name: OList, OList Item, UList, UList Item

OList

UList

OList Item, UList Item

If a custom style name is assigned to a List, that style name will still inherit all of the listed default style information.